Emirates ID Verification API - v2

This document outlines the details of the Emirates ID Verification API - v2.

API Description

Objective

The Emirates ID Verification API provides detailed information about a user's Emirates Identity Card.

Input	Output
The user's Emirates ID number, date of birth, and current nationality	The Details associated with the user's Emirates ID. The complete list of output fields is available in the Success Response Details section

Did You know?

The Emirates ID (also known as Emirates Identity Card or EID) is a mandatory identification card for citizens and residents of the United Arab Emirates (UAE). It's managed by the Federal Authority for Identity, Citizenship, Customs and Port Security (ICP) and is essential for accessing government services, legal processes, and other key functions in the UAE.
The Emirates ID Number is a unique 15-digit number printed on the citizen's Emirates ID card.

API URL

https://ind-thomas.hyperverge.co/v1/emiratesVerificationV2

API Endpoint

emiratesVerificationV2

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and ﬁles as form-data through a POST request.

Authentication

You need a unique pair of application ID ( appId ) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

API Request Details

Method - `POST`

Headers

Parameter	Mandatory or Optional	Description	Valid Values
`content-type`	Mandatory	This parameter defines the media type for the request payload.	application/json
`appId`	Mandatory	The application ID shared by HyperVerge	Not Applicable - this is a unique value
`appKey`	Mandatory	The application key shared by HyperVerge	Not Applicable - this is a unique value
`transactionId`	Mandatory	The unique ID for the customer journey.	Not Applicable - this is a unique value related to a transaction in your application

Input

The following table provides the details of the parameter required for the API's request body:

Parameter	Mandatory or Optional	Description	Allowed Values	Default Value
`idNumber`	Mandatory	The valid Emirates ID Number	Format: A unique 15-digit number	Not Applicable
`dateOfBirth`	Mandatory	The date of birth of the user	Format: DD-MM-YY	Not Applicable
`currentNationality`	Mandatory	The current nationality of the user	Refer to the list of nationalities that are allowed for this parameter here.	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the API:

curl --location --request POST 'https://ind-thomas.hyperverge.co/v1/emiratesVerificationV2' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "idNumber": "<Enter_the_valid_ID_Number>",
    "dateOfBirth": "<Enter_DD-MM-YY_format>",
    "currentNationality": "<Enter_the_users_current_nationality>"
}'

Success Responses

The following code snippet demonstrates a success response from the API:

{
    "status": "success",
    "statusCode": 200,
    "result": {
        "dateOfBirth": "<User's_DOBin_YYYY-MM-DD_Format>",
        "currentNationality": "<User's_Current_Nationality>",
        "issueDate": "<Issue_Date_in_YYYY-MM-DD_Format>",
        "expireDate": "<Expiry_Date_in_YYYY-MM-DD_Format>",
        "unifiedNumber": "<Unified_Number>",
        "passportExpiryDate": null,
        "status": "<Document_Status>",
        "fileNumber": "<Document_Status>"
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Success Response Details

The following table outlines the details of the success response from the API:

Parameter	Type	Description
status	string	The status of the API response
statusCode	integer	The HTTP status code of the API response
dateOfBirth	string	The date of birth of the user in YYYY-MM-DD format
currentNationality	string	The user's current nationality
issueDate	string	The date on which the Emirates ID was issued in YYYY-MM-DD format
expireDate	string	The expiry date of the Emirates ID in YYYY-MM-DD format
unifiedNumber	string	The unified number associated with the Emirates ID
passportExpiryDate	string	The expiry date of the user's passport
status	string	The current status of the Emirates ID
fileNumber	string	The file number associated with the Emirates ID application
requestId	string	The unique identifier for the API request
transactionId	string	The unique transaction identifier passed in the request header

Error Responses

The following are some error responses from the API:

Invalid ID Number
Missing/Invalid Credentials
Incorrect Format for ID Number
Missing Input

{
    "status": "failure",
    "statusCode": 400,
    "error": "The ID number is invalid",
    "metaData": {
       "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

{
    "message": "Missing/Invalid credentials",
    "statusCode": 401,
    "status": "failure"
}

{
    "status": "failure",
    "statusCode": 422,
    "error": "Enter valid 15 digit ID number",
    "metaData": {
       "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

{
    "status": "failure",
    "statusCode": 422,
    "error": "ID number should not be empty",
    "metaData": {
       "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Incorrect DOB Format
Incorrect Nationality
Internal Server Error

{
    "status": "failure",
    "statusCode": 422,
    "error": "Please provide the dateOfBirth in DD-MM-YYYY format.",
    "metaData": {
       "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

{
    "status": "failure",
    "statusCode": 422,
    "error": "Nationality not found",
    "metaData": {
       "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

{
  "status": "failure",
  "statusCode": 500,
  "message": "internal server error"
}

Error Response Details

A failure or error response from the module contains a failure status, with a relevant status code and error message.
The following table lists all error responses:

Status Code	Error Message	Error Description
400	The ID number is invalid	The input ID number is invalid or does not exist
401	Missing/Invalid credentials	The request is either missing the mandatory `appId` and `appKey` combination or has invalid values
422	Enter valid 15 digit ID number	The ID number provided is not in the required numeric format; it contains fewer or more than 15-digits, has alphabets, or special characters
422	ID number should not be empty	The request was made without providing the required ID number
422	Please provide the dateOfBirth in DD-MM-YYYY format	The date of birth entered is not in the required DD-MM-YYYY format
422	Nationality not found	The Nationality entered is invalid or does not exist
500	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution

API Description​

Objective​

API URL​

API Endpoint​

Overview​

Authentication​

API Request Details

Method - POST

Headers

Input​

Request​

Success Responses​

Success Response Details​

Error Responses​

Error Response Details​